# 弘则 MCP 注册与接入引导指南

弘则 MCP 提供研究报告、产业材料和金融数据，支持 OAuth 授权和用户 token 接入。

## 接入信息

| 用途 | 入口或配置 |
|---|---|
| 服务名称 | 弘则 MCP / Horizon Insights |
| 服务首页 | [弘则 MCP](https://vmcp.hzinsights.com/) |
| 注册 / 登录 | [登录用户中心](https://vmcp.hzinsights.com/auth) |
| 用户中心 | [用户中心](https://vmcp.hzinsights.com/dashboard) |
| 创建与管理用户 token | [接口令牌](https://vmcp.hzinsights.com/dashboard?tab=tokens) |
| 官网接入说明 | [接入指南](https://vmcp.hzinsights.com/guide) |
| 数据与工具说明 | [工具文档](https://vmcp.hzinsights.com/docs) |
| MCP 服务地址 | `https://vmcp.hzinsights.com/mcp/` |
| 传输协议 | Streamable HTTP（HTTP / 流式 HTTP） |
| 认证方式 | OAuth 授权或用户 token（Bearer） |

## 一、确认接入状态

1. 检查当前会话是否已连接弘则 MCP，已有可用连接时直接开展研究。
2. 需要新连接时，根据客户端的连接设置、对应版本官方文档及用户偏好，确定认证方式。客户端信息不明确时，询问应用名称与版本；没有远程 MCP 接入入口时，引导用户选择支持远程 MCP 的客户端。
3. 按选定的认证方式引导用户完成接入：

| 认证方式 | 接入步骤 |
|---|---|
| OAuth | 在客户端添加服务并发起授权 → 用户在弘则页面登录或注册并确认授权 → 返回客户端验证连接 |
| 用户 token | 登录用户中心（尚未注册时先注册）→ 使用已有 token 或创建 token → 配置客户端并验证连接 |

## 二、注册与登录

手机号首次验证会完成注册，已有账号则直接登录。

1. 打开[注册 / 登录页面](https://vmcp.hzinsights.com/auth)，选择“手机验证码”。
2. 选择国家或地区，填写手机号，点击“获取验证码”。
3. 用户在官网输入验证码，点击“登录 / 注册”，随后进入用户中心或继续原来的 OAuth 授权流程。

已登录的用户可直接继续连接。已开通邮箱账号的用户也可选择“邮箱验证码”登录。

## 三、OAuth 连接

服务支持授权发现、动态客户端注册（DCR）、Authorization Code + PKCE 和凭据刷新。由客户端完成授权并管理凭据。

Agent 根据用户当前客户端、版本和官方文档提供设置步骤。需要用户手动配置时，引导其添加服务并启用连接器；用户在弘则页面完成登录和授权后，返回客户端验证连接。

| 授权发现信息 | 地址 |
|---|---|
| MCP 资源元数据 | [资源发现地址](https://vmcp.hzinsights.com/server/.well-known/oauth-protected-resource/mcp) |
| OAuth 授权服务器元数据 | [授权服务发现地址](https://vmcp.hzinsights.com/server/.well-known/oauth-authorization-server) |

## 四、用户 token 连接

### 创建用户 token

已有有效用户 token 时可直接配置。需要创建时：

1. 登录[接口令牌页面](https://vmcp.hzinsights.com/dashboard?tab=tokens)，点击“新建令牌”。
2. 填写用途名称，例如“个人研究环境”，点击“确认创建”。
3. 复制并保存生成的 token。完整 token 只展示一次。

### 配置客户端

使用上方的 MCP 服务地址和 Streamable HTTP 协议。客户端提供 Token 输入框时，按字段说明填写；使用自定义请求头时，设置 `Authorization: Bearer <USER_TOKEN>`。

支持 `mcpServers` 格式的客户端可参考以下配置，将 `<USER_TOKEN>` 替换为自己的 token；具体字段和密钥引用方式按客户端规范填写。

```json
{
  "mcpServers": {
    "vmcp": {
      "type": "http",
      "url": "https://vmcp.hzinsights.com/mcp/",
      "headers": {
        "Authorization": "Bearer <USER_TOKEN>"
      }
    }
  }
}
```

将 token 保存到客户端的凭据配置中，保存后重新加载 MCP 连接。

## 五、验证连接

1. 由客户端完成 MCP `initialize` 与初始化通知。
2. 通过 `tools/list` 读取工具名称、说明和输入参数。当前会话尚未加载连接时，按客户端要求刷新连接或开启新会话。
3. 成功获取工具目录后，告知用户连接完成并继续研究任务；用户尚未提出任务时，可参考后文案例推荐问题。

使用当前连接返回的工具目录开展查询。OAuth 授权可在用户中心的“已连接应用”中管理，自建令牌可在“接口令牌”中管理。

## 能查哪些数据

弘则 MCP 可用于检索研究与原文、获取金融数据、制作比较表和计算指标。

| 数据或材料 | 能得到什么 | 主要工具 | 使用范围与口径 |
|---|---|---|---|
| 证券身份与公司资料 | 股票、指数、宏观指标代码；公司简介和行业分类 | `search_code`、`get_basicinfo` | 代码查询覆盖 A 股、美股、港股、指数及宏观指标；`get_basicinfo` 仅 A 股 |
| 股票与指数行情 | 历史开高低收、成交量及可用扩展字段，可计算区间表现 | `get_stock_market_history` | A 股、美股、港股、指数；核对复权方式和实际覆盖日期 |
| 估值与历史位置 | PE、PB、估值分位及可用股息率字段 | `get_stock_valuation_history` | A 股、美股、港股、指数；分位以 0–1 小数表示 |
| 财务报表与主营构成 | 营收、利润、资产负债、现金流、分产品/分地区收入等 | `get_financial_data` | A 股、美股、港股，具体字段覆盖不同；精简报表也提供必要语义说明，`full` 保留原始全字段 |
| 财务比率与增长 | ROE、ROA、毛利率、净利率、资产负债率、增长前后绝对值 | `get_financial_ratios`、`get_financial_growth` | 按市场、报告期及增长口径组织比较 |
| 盈利预测 | 预测收入、利润、FY1/FY2，以及可用的区间和分析师数 | `get_stock_forecast_history` | A 股盈利预测历史观测；美股未来财年一致预期快照 |
| 美股公司与分析师信息 | 公司档案、报价快照、多周期涨跌幅、评级、目标价、财报预期差 | `get_stock_company_snapshot`、`get_stock_analyst_opinion` | 仅美股；各数据集日期可能不同，盘中快照与日线收盘需区分 |
| 宏观与产业指标 | M2、CPI、PMI、GDP、汇率，以及库中覆盖的商品价格、产量、库存等序列 | `search_code` → `get_macro_data` | 先确认指标名称、单位、频率与来源，覆盖以实际检索为准 |
| 期货期现结构 | 合约目录、OHLCV、持仓、结算、基差、跨期价差、主连换月映射 | `list_futures_contracts`、`get_futures_market_history`、`get_futures_basis`、`get_futures_calendar_spread`、`get_futures_rolling_map` | 区分主连与具体合约、现货口径、近远月顺序、收盘与结算 |
| 指数成份与相对收益 | 指定时点成份股/权重；个股相对申万行业的历史超额收益 | `get_index_components`、`get_stock_excess_return` | 超额收益工具仅 A 股，核对实际基准日与可用交易日 |
| 弘则研究与图表 | 报告目录、研究框架、报告全文、图表定义及底层数据 | `get_research` → `get_article`；`search_chart` → `get_chart_settings` → `get_chart_data` | 按主题发现研究，结合发布日期选择材料，按授权读取内容 |
| 产业材料与原话 | 调研、专家交流、渠道反馈、快讯；A 股官方 IR；美股电话会 | `search_field_notes` → `get_field_note`；`search_cn_transcript`；`search_us_transcript` | 根据具体材料判断来源属性；产业转述与公司正式披露分开 |
| 日报与新闻 | 跨行业主题、主体、涨价线索；外部财经新闻和来源链接 | `get_daily_overview`、`search_news` | 日报默认最新可用日期；可继续按主题阅读原文与新闻 |
| 自然语言取数与筛选 | 综合取数、指标目录、多条件候选、自然语言策略探索 | `get_data`、`list_indicators`、`screen_stocks`、`get_strategy` | 明确标的、字段与时间范围；结果附实际报告期和观察区间 |

## 典型研究场景与提问示例

### 1. 核验新业务到了哪一步：帝尔激光 BC、TGV、PCB

**怎么问：**“分别列出三项业务的送样、出货、复购、订单和收入证据，并给出管理层原话、交流日期与来源。”

**调用方式：**先用 `search_cn_transcript`，按 `stock_name` 或确认后的 `trade_code` 限定公司，用 BC、TGV、PCB 等主题分别检索，并设置所需日期范围；补充市场线索时使用 `search_field_notes` → `get_field_note`。

**预期产出：**`业务 → 商业化阶段 → 管理层原句 → 材料日期 → 来源 → 后续观察点` 对照表，分别列出送样、出货、复购、订单和收入证据。

### 2. 把公司比较落实到利润与现金：平高电气和思源电气

**怎么问：**“用同一交易日价格和可比报告期，对比两家的收入、归母净利润、经营现金流与估值，解释差异的依据。”

**调用方式：**`search_code` 确认两家公司 → 分别取 `get_stock_market_history`、`get_stock_valuation_history`、`get_financial_data`。精简报表已附单位、币种、归属与逐期口径；查看 `field_definitions` 和 `reporting_periods`，原始字段核查可补 `data_type="full"`。归母/扣非归母字段为 null 时不得用净利润替代。业务差异可补官方 IR 或年报。

**预期产出：**同日价格、同口径利润与现金流比较表，解释经营表现、现金回收和估值差异。TTM、全年、半年累计分别列明。

### 3. 反算现价需要什么条件：汇川技术与先导智能

**怎么问：**“汇川在 20、25、30 倍退出市盈率下，需要怎样的盈利水平才能满足给定回报目标？”或“先导的经营恢复体现在哪些报表项目，现价要达到 10% 总回报需要什么条件？”

**调用方式：**`get_stock_market_history` 取得指定日未复权收盘价，`get_financial_data` 取得明确报告期的归母利润、现金流与相关科目。股本和 EPS 定义须核对，再由 Agent 在本地计算情景表。

**预期产出：**`持有期 → 回报目标 → 假设退出 PE → 所需 EPS → 对盈利基数的增幅` 的情景表。忽略分红、费用且股本固定时，总回报目标为 `R`、现价为 `P0`，可用 `目标 EPS = P0 × (1 + R) / 退出 PE`；若目标是持有 `n` 年的年化回报 `r`，将 `(1 + R)` 换成 `(1 + r)^n`。表中注明持有期、股本及分红假设。

### 4. 分开看已实现业绩、预期修正和估值：澜起科技与聚辰股份

**怎么问：**“最近几个报告期的盈利兑现如何？两个观测日之间盈利预期上修还是下修？同日估值怎样？”

**调用方式：**对每家公司分别用 `get_financial_data` 取实际财务、`get_stock_forecast_history` 取 A 股预测历史、`get_stock_valuation_history` 取估值；先锁定比较日期与目标财年，再拼表。

**预期产出：**实际业绩、带观测日的盈利预测和同日估值对照表；FY1/FY2 映射到具体目标年份。也可用于分析英科医疗的预期变化、生益科技的估值位置。

### 5. 拆解需求与经营恢复：医疗设备、高值耗材

**怎么问：**“用联影、迈瑞、南微、惠泰近若干季度的收入、利润、毛利率和现金流，判断恢复体现在哪些环节，再找公司对量价变化的解释。”

**调用方式：**`search_code` → 逐公司 `get_financial_data`、`get_financial_ratios` → `search_cn_transcript`；需要行业框架时补 `get_research` → `get_article`。

**预期产出：**跨公司季度趋势表，结合业绩交流材料解释量价、需求和回款变化。A 股累计报表转换为单季后，计算同季同比。

### 6. 做可计算的业务结构表：海外收入、产品与地区

**怎么问：**“比较中际旭创、天孚通信等公司两年的海外收入占比。”或“药明康德不同地区业务的收入和毛利率怎样变化？”

**调用方式：**确认代码后，逐公司调用 `get_financial_data(data_type="segment")`，指定年份或报告日期；总收入用同口径报表核对。字段清楚、范围小时也可用 `get_data` 提出明确的公司、年份和字段要求，再检查返回的公司×期间是否齐全。

**预期产出：**`公司 → 年份 → 地区/产品 → 收入 → 占比 → 毛利率（如有）→ 单位与来源` 业务结构表，统一分部定义、报告期与单位。

### 7. 读取弘则框架，再用新证据检验：存储、黑色、财政与债券

**怎么问：**“弘则如何分析存储涨价的持续性？”或“弘则对财政发行、资金面和股债关系有哪些研究框架？列出报告日期，并精读相关原文。”

**调用方式：**向 `get_research` 传完整研究问题，查看标题、日期和来源类型；从 article 类型结果取真实 `article_id` 调用 `get_article`。先精读最相关的 1–3 篇，再用产业材料、官方口径和数据序列补充后续变化。

**预期产出：**`核心观点 → 依据 → 成立条件 → 后续观察变量 → 支持/反证`，每条观点关联报告名称与发布日期。例如精读《久期仍在胜出》一类专题报告，或把多篇存储、黑色研究组织成主题框架，再用后续材料跟踪观点演进。

### 8. 从产业线索回到原文：振华金属铬、液冷与机器人

**怎么问：**“振华股份金属铬的订单和提价线索有哪些，哪些是正式披露、哪些是交流转述？”或“液冷从单相向两相演进，有哪些原始材料支持？”

**调用方式：**用 `search_field_notes` 对短核心词分别检索，小 `limit` 探查后用 `get_field_note` 读全文；对公司正式说法补 `search_cn_transcript`，必要时回到公司公告或官方文件。研究机器人价值量时也可用此流程核对零件价格、送样与定点进度。

**预期产出：**`研究线索 → 材料出处 → 日期 → 原句 → 来源类型 → 后续观察点` 清单，分别呈现公司披露、产业交流与分析情景；同源材料按原始出处归并。

### 9. 查海外管理层原话：美光 HBM、英伟达数据中心

**怎么问：**“美光管理层如何谈 HBM 供给与收入？”或“英伟达电话会如何解释数据中心增长与 Blackwell 需求？给日期、原句与上下文。”

**调用方式：**向 `search_us_transcript.keyword` 传入独立完整问题，保留公司名称/代码、主题、必要时间和想了解的原因/比较等语境；追问由调用方补齐指代，不附整段聊天或补造前提。快速定位使用 `content_mode="matched"`、`limit=1–3`；专题精读使用 `content_mode="full"`、`limit=1`。查看 snippet_status/snippet_truncated：主题窗口不保证问题已完整回答，未定位时不返回开头，不能据此判断公司从未讨论；仅公司查询的matched片段为空。正文定位支持有限的中英财务术语，必要时补充英文主题。从返回材料中选择符合研究时间范围的会议，并结合全文上下文整理管理层表述。

**预期产出：**带会议日期、原句、上下文与出处的证据表，保留返回的句子编号，按会议时间比较 HBM 供给、产品需求及资本开支等表述的变化。

### 10. 看懂商品期现结构：铜、豆粕、螺纹钢

**怎么问：**“最近一个月行情、基差与近远月价差怎样变化？给两腿价格、合约、日期和单位，收盘与结算分开。”

**调用方式：**先 `list_futures_contracts` 确认代码，再用 `get_futures_market_history` 取行情；品种基差用 `get_futures_basis`，品种近远月价差用 `get_futures_calendar_spread`；涉及主连跳变时加 `get_futures_rolling_map`。

**预期产出：**行情、现货腿/期货腿、近月腿/远月腿及差值的同日表。收盘与结算分别计算，用于跟踪升贴水和期限结构。

指定两张合约时，分别取得对应合约的同日价格再计算价差；品种结构观察则可直接使用品种基差与跨期价差工具。跨期价差按近月减远月解释，基差采用返回的现货规格、地区和计算方向。主连换月映射用于连接连续序列与具体合约。

### 11. 把产业链和宏观序列放进同一观察面板

**怎么问：**“铁水、表需、库存和利润的最新组合说明什么？”或“把美元指数、美元兑人民币、制造业/服务业 ISM、非农、失业率放进同一观察面板。”

**调用方式：**对每个指标单独 `search_code`，确认标准名、单位和来源，再分别 `get_macro_data`；研究图表使用发现、参数、数据三步，取得目标区间的序列后制作观察面板。

**预期产出：**`指标 → 定义 → 单位 → 频率 → 最新观测日 → 当前值 → 可比变化 → 来源` 观察面板，保留日度、周度或月度频率，分别注明盘面利润与现货利润的定义。

### 12. 判断风格是否扩散，并取得完整历史行情

**怎么问：**“最近一周是大盘权重更强，还是向中小盘扩散？用同一区间的指数涨跌与成交额说明。”也可继续问：“取五年历史，计算 20/60 日波动和历史分位。”

**调用方式：**`search_code` 确认上证 50、沪深 300、中证 500、中证 1000 等指数代码，分别用 `get_stock_market_history` 取同窗口数据，再本地计算；需要成份权重时用 `get_index_components`，需要 A 股个股相对行业表现时用 `get_stock_excess_return`。

**预期产出：**日/周窗口的指数相对表现表，以及用于计算波动和分位的历史面板。市场宽度分析可结合上涨家数等指标；跨标的比较时完整读取分页，统一复权、日期与统计分母。

### 13. 复用研究图表：行业现金流、PMI、股东增减持

**怎么问：**“哪些行业收入增长但经营现金回款背离？”“有没有 PMI 新订单与新出口订单的长期图表？”“取重要股东增减持净额的底层数据。”

**调用方式：**`search_chart` 按主题找图 → 检查标题和说明是否相关 → `get_chart_settings` 读参数及候选值 → 用真实 `varname` 填写 `selection_values` → `get_chart_data`。

**预期产出：**图表定义、参数和底层数据；行业财报汇总附报告期、披露比例与样本定义。无需调参的图表可直接读取数据。

### 14. 从日报发现选题，再回原文验证

**怎么问：**“最新可用日报里有哪些主题变化和涨价线索？挑三条，给原始材料、涉及公司和下一步验证点。”

**调用方式：**`get_daily_overview` 先看最新可用日期和主题；需要正文时设 `include_content=true`。对选中的主题用 `search_field_notes` → `get_field_note` 深入，按需要补官方 IR、电话会、行情或外部新闻。

**预期产出：**`主题 → 线索 → 原始来源 → 涉及对象 → 事实依据 → 后续观察点` 清单。查询指定日期时传 `end_date`；跨日扫描按返回的实际日报日期组织材料。

## 查询与结果整理

1. **先确认研究对象。** 股票、指数和宏观指标先用 `search_code`；期货先查合约目录；图表先搜索。采用返回的代码、文档 ID 和图表参数，并在同一任务中复用已确认的对象。
2. **按材料类型选择入口。** 产业调研、专家交流用 `search_field_notes`；A 股官方 IR 用 `search_cn_transcript`；美股电话会用 `search_us_transcript`；弘则观点用 `get_research`。检索后按需读取全文。
3. **明确查询范围。** 查询中注明公司、指标、日期和报告期。多公司按标的分别取数并对齐；长历史按分页或日期分段取全；自然语言综合取数明确所需字段与输出表形态。
4. **使用结构化数据计算。** 优先解析 `structuredContent`；`compact_table` 按 `columns` 与 `rows` 配对恢复表格。用数值表计算比例、增幅和比较结果，并保留公式与数据来源。
5. **带上日期与单位。** 分别记录交易日、报告期、披露日、会议日与预测观测日，按实际覆盖范围展示数据。跨市场比较保留币种、单位及复权定义。
6. **统一财务口径。** `get_financial_growth` 默认 `comparison=yoy`，全年对上一年全年、上半年对上一年上半年，美股按财政年和报告期配对。`period_type=report` 保留原始报告口径，`annual` 只取全年；环比 `comparison=qoq` 必须选择 `quarter`（单季）或 `half_year`（单半年）。按现有数据约定，A 股/港股累计流量通过相减还原单季，H2=全年−H1；美股单半年由两个独立单季相加。资产、权益始终用期末值，净利润不统一为归母口径。`start_date/end_date` 筛选本期报告结束日期，对比期另取；`periods` 表示本期期数上限，不代表固定年数。缺期、缺换算组成值或零/负基数时返回空增长率和 `*_status`。上游真实财政期及单位仍需核对，日期筛选不等于历史已披露信息回测。
7. **明确估值、预测与筛选的时间维度。** FY1/FY2 映射到具体目标年；估值分位按 0–1 转换，例如 0.4372 对应 43.72%。`screen_stocks` 的四个条件数组保持等长，`latest_only=true` 先确定库内最新报告期/估值日期再筛选，时间位移必须全为 0，缺失不回退旧值；结果附逐指标日期、状态、覆盖统计及独立诊断。`unverified` 表示更新及时性未确认；默认排除超龄/估值日期落后记录，只有明确接受旧数据才设置 `stale_policy=include`。`report_date` 可固定财务报告期，估值仍取最新库内日期。历史曾满足条件请用 `latest_only=false`，年份位移不是盈利预测。
8. **按证据组织回答。** 结果包含核心结论、数据或原文证据、计算方法与情景假设。引用保留出处和日期，分别说明公司披露、产业转述与分析判断。

### 读取调用状态

先读 `outcome.status`：`success` 完成、`empty` 无结果、`partial` 部分完成、`error` 失败。`no_match` 是没有匹配项，`data_missing` 是缺数据，不能混为一谈。`partial` 保留已取得数据，应根据 `issues[].scope/code/retryable` 仅补查未完成部分；根级 retryable 表示是否原样重跑整次调用，partial 固定为 false。没有自动续跑 token，不要无限重试。

HTTP 外层新增 outcome/issues，旧 result 文本或列表类型保留；完整失败返回 4xx/5xx，但仍须读取 JSON 详情。MCP 使用 structuredContent 与 isError；empty/partial 不设置 isError。get_data 旧 status 仅表示停止原因，辅助查找、超时、模型自然结束不代表业务完成。分页 has_more 表示下一页，正常分页不算部分失败。

研究/策略工具正常返回非空回复、没有已知未解决问题时标为 success；已执行查询但没有结果时标为 empty。明确发生失败、超时或达到执行上限时，已有业务数据则标 partial，否则标 error；原文本和已取得数据继续保留。相同工具、相同参数的重试成功会清除该请求的旧失败。正常结束不再自动标注 completion_unverified，也不额外调用 LLM 审核完整性。success 只表示正常执行结束，不承诺回答覆盖全部业务要求。

### 财务字段与参数口径

精简财报也返回单位、币种、累计/单季及权益归属说明；美股每期报表币种来自 REPORTEDCURRENCY，港股没有来源依据时标为未确认，不能统一当港币。net_profit 是来源净利润，不能直接解释为归母净利润；net_profit_parent 和扣非归母字段缺少可核验来源时为 null，并保留原因。港股普通股东净利润单列 net_profit_common；equity 为兼容字段，实际归属见说明，parent_equity 与 total_equity 只按独立来源提供。

美股标准报表 annual_only=true 按 FY 取年报，报告结束日期不必是12-31；false取独立单季。fiscal_year 按财政年筛选；A股/港股目前按报告日期年份。periods 是报告记录数，不等于固定季度数或年数。主营构成和美股专属扩展类型不接受 annual_only=true；没有财政年字段的扩展类型请改用日期范围。报表类型以工具 schema 的枚举为准，拼错将返回 invalid_argument，不再自动返回总览。